<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Debugger: Editing Machine State</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY lang="EN-US">
    <H1><A name="plugin"></A>Debugger: Control and Machine State</H1>

    <P>This plugin presents actions for controlling targets and modifying machine state. It
    provides a drop-down action in the main toolbar for choosing what to control for the current
    target: The live target, the integrated emulator, or the recorded trace. Only those control
    actions suitable for the selection are displayed. Machine-state edits and breakpoint commands
    throughout the UI are directed accordingly.</P>

    <H2>Actions</H2>

    <P>The plugin provides several actions, but only certain ones are displayed, depending on the
    current mode.</P>

    <H3><A name="control_mode"></A>Control Mode</H3>

    <P>This action changes the mode for the active trace and, if applicable, its associated live
    target. It is always displayed, but only available when a trace is active. The possible modes
    are:</P>

    <UL>
      <LI><IMG alt="" src="icon.debugger.control.mode.ro.target"> <B>Control Target w/Edits
      Disabled:</B> The default, this presents actions for controlling the live target but rejects
      all machine-state edits. Breakpoint commands are directed to the live target. When active,
      the UI automatically follows the latest snapshot recorded, and navigating back in time is not
      permitted. If the target is terminated and the trace remains open, the mode is automatically
      switched to <B>Control Trace</B>.</LI>

      <LI><IMG alt="" src="icon.debugger.control.mode.rw.target"> <B>Control Target:</B> This
      presents actions for controlling the live target and directs edits to the live target.
      Breakpoint commands are directed to the live target. When active, the UI automatically
      follows the latest snapshot recorded, an navigating back in time is not permitted. If the
      target is terminated and the trace remains open, the mode is automatically switched to
      <B>Control Emulator</B>.</LI>

      <LI><IMG alt="" src="icon.debugger.control.mode.ro.trace"> <B>Control Trace w/Edits
      Disabled:</B> This presents actions for navigating trace snapshots but rejects all
      machine-state edits. Breakpoint commands are directed to the emulator.</LI>

      <LI><IMG alt="" src="icon.debugger.control.mode.rw.trace"> <B>Control Trace:</B> This
      presents actions for navigating trace snapshots. It directs all edits to the trace database.
      Edits are generally always accepted, and they are applied directly to the trace. Breakpoint
      commands are directed to the emulator.</LI>

      <LI><IMG alt="" src="icon.debugger.control.mode.rw.emulator"> <B>Control Emulator:</B> This
      presents actions for controlling the integrated emulator. Breakpoint commands are directed to
      the emulator. This can be used for interpolating and extrapolating execution from the current
      snapshot, without affecting the live target. It directs edits to the integrated emulator by
      generating patch steps and appending them to the emulation schedule. See the <A href=
      "help/topics/DebuggerTimePlugin/DebuggerTimePlugin.html#goto_time">Go To Time</A> action.
      Essentially, the change is applied in the trace's scratch space, leaving the original
      recording in tact. Due to implementation details, a thread must be selected, even if edits
      only affect memory. Additionally, the disassembly context register cannot be modified.</LI>
    </UL>

    <H2>Target Control Actions</H2>

    <P>These actions are visible when a <B>Control Target</B> mode is selected. They are available
    only when the current trace has an associated live target. Commands are directed to the focused
    object or a suitable substitute.</P>

    <H3><A name="target_resume"></A><IMG alt="" src="icon.debugger.resume"> Resume</H3>

    <P>Allow the current target to resume execution. Other debuggers may call this "continue" or
    "go." If successful, the target enters the "running" state until it is interrupted or
    terminated. This is available when the target is currently stopped.</P>

    <H3><A name="target_interrupt"></A><IMG alt="" src="icon.debugger.interrupt"> Interrupt</H3>

    <P>Interrupt the current target's execution. Other debuggers may call this "break," "suspend,"
    or "stop." If successful, the target enters the "stopped" state. This is available when the
    target is currently running.</P>

    <H3><A name="target_kill"></A><IMG alt="" src="icon.debugger.kill"> Kill</H3>

    <P>Kill the current target. Other debuggers may call this "terminate" or "stop." This may
    consequently close the current trace. If successful, the target enters the "terminated" state.
    This is always available for a live target.</P>

    <H3><A name="target_disconnect"></A><IMG alt="" src="icon.debugger.disconnect"> Disconnect</H3>

    <P>Disconnect from the current target's debugger. This usually causes the connected debugger to
    terminate and likely kill its targets. This may consequently close the current trace (and
    perhaps others). This is always available for a live target.</P>

    <H3><A name="target_step_into"></A><IMG alt="" src="icon.debugger.step.into"> Step Into</H3>

    <P>Step the current target to the next instruction. This is available when the target is
    currently stopped. If successful the target may briefly enter the "running" state.</P>

    <H3><A name="target_step_over"></A><IMG alt="" src="icon.debugger.step.over"> Step Over</H3>

    <P>Step the current target to the next instruction in the current subroutine. This is available
    when the target is currently stopped. If successful the target may briefly enter the "running"
    state.</P>

    <H3><A name="target_step_out"></A><IMG alt="" src="icon.debugger.step.finish"> Step Out</H3>

    <P>Allow the current target to finish the current subroutine, pausing after. This is available
    when the target is currently stopped. If successful the target may briefly enter the "running"
    state.</P>

    <H3><A name="target_step_last"></A><A name="target_step_ext"></A><IMG alt="" src=
    "icon.debugger.step.last"> Step Extended (Repeat Last)</H3>

    <P>Perform a target-defined step, perhaps the last (possibly custom) step. This is available
    when the target is currently stopped. If successful the target may briefly enter the "running"
    state.</P>

    <H2>Trace Navigation Actions</H2>

    <P>These actions are visible when a <B>Control Trace</B> mode is selected. They are available
    when there is an active trace.</P>

    <H3><A name="trace_snap_backward"></A><IMG alt="" src="icon.debugger.snap.backward" width="16">
    Snapshot Backward</H3>

    <P>This activates the previous snapshot. All windows displaying machine state will show that
    recorded in the activated snapshot. This is available only when there exists a snapshot
    previous to the current.</P>

    <H3><A name="trace_snap_forward"></A><IMG alt="" src="icon.debugger.snap.forward" width="16">
    Snapshot Forward</H3>

    <P>This activates the next snapshot. All windows displaying machine state will show that
    recorded in the activated snapshot. This is available only when there exists a snapshot after
    the current.</P>

    <H2><A name="emu_actions"></A>Emulation Actions</H2>

    <P>These actions are visible when the <B>Control Emulator</B> mode is selected. They are
    available when there is an active trace. Commands are directed to the integrated emulator for
    the current trace.</P>

    <H3><A name="emu_resume"></A><IMG alt="" src="icon.debugger.resume"> Resume</H3>

    <P>Allow the emulator to resume execution. This is available when no other integrated emulator
    is running. A monitor dialog is presented during execution, but the GUI remains responsive.
    Only one emulator can be run from the GUI at a time. If the current snapshot represents the
    live target, the emulator may read additional machine state from the live target. For
    non-contrived programs, the emulator will likely be interrupted, since some instructions and
    system calls are not yet supported. It could also start executing from unmapped memory or enter
    an infinite loop. If it seems to carry on too long, interrupt it and examine.</P>

    <H3><A name="emu_interrupt"></A><IMG alt="" src="icon.debugger.interrupt"> Interrupt</H3>

    <P>Interrupt the currently-running emulator. This is available when any integrated emulator is
    running. In most cases, this is the emulator for the current trace, but it may not be.
    Canceling the dialog for an emulation task will also interrupt the emulator. Upon interruption,
    the emulation schedule is noted and the snapshot displayed in the GUI.</P>

    <H3><A name="emu_step_back"></A><IMG alt="" src="icon.debugger.step.back"> Step Back</H3>

    <P>Steps the emulator to the previous instruction, by flow. This is available when the current
    snapshot includes emulated steps. This operates by repeating the current emulation schedule
    with one less step. Thus, it effectively steps backward, heeding the proper control flow. While
    not common, if emulation to the current snapshot took a good bit of time, then stepping
    backward will likely take about the same amount of time.</P>

    <H3><A name="emu_step_into"></A><IMG alt="" src="icon.debugger.step.into"> Step Into</H3>

    <P>Steps the emulator to the next instruction, by flow. This is available when there is an
    active thread. At worst, this operates by repeating the current emulation schedule with one
    more step of the current thread. In most cases, this can use the cached emulator for the
    current snapshot and advance it a single step. Note that "Step Over" is not currently supported
    by the emulator.</P>

    <H3><A name="emu_skip_over"></A><IMG alt="" src="icon.debugger.skip.over"> Skip Over</H3>

    <P>Skips the emulator over the current instruction, ignoring flow. This is available when there
    is an active thread. At worst, this operates by repeating the current emulation schedule with
    an added skip for the current thread. In most cases, this can use the cached emulator for the
    current snapshot and advance it by skipping once. Note that this <EM>skips</EM> the
    instruction. Thus, when used on a "call" instruction, all effects and side-effects of the
    subroutine are averted. This is not the same as "<EM>Step</EM> Over," which is not currently
    supported by the emulator.</P>

    <H2>Recommendations</H2>

    <P>The default mode is <B>Control Target w/Edits Disabled</B>, because in most cases, this is
    the desired behavior. When the target dies, the mode becomes <B>Control Trace w/Edits
    Disabled</B>. For the most part, modifying the recorded trace itself is discouraged. There are
    few reasons to edit a trace, perhaps including 1) Hand-generating an experimental trace; 2)
    Generating a trace from a script, e.g., importing an event log, recording an emulated target;
    3) Patching in state missed by the original recording. Be wary of <B>Control Trace</B> mode,
    especially after emulating, since you could accidentally edit scratch space in the trace. It is
    allowed but can produce non-intuitive and erroneous results, since the emulator caches its
    snapshots in scratch space.</P>

    <P>To modify state in a live target, use the <B>Control Target</B> mode. <B>NOTE:</B> Some UI
    components will also require you to toggle a write protector. This also affects scripts that
    use the state editing service. However, disabling edits cannot prevent a script from directly
    accessing Ghidra's Target API to modify a target. Nor can it prevent edits via the connected
    debugger's command-line interpreter. The following components all use the service: <A href=
    "help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Dynamic Listing</A>, <A href=
    "help/topics/DebuggerMemoryBytesPlugin/DebuggerMemoryBytesPlugin.html">Memory (Dynamic
    Bytes)</A>, <A href=
    "help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A>, and <A href=
    "help/topics/DebuggerWatchesPlugin/DebuggerWatchesPlugin.html">Watches</A>.</P>
  </BODY>
</HTML>
